home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Auge 4000 / Auge 4000 #14 (1987-12-23)(Amiga User Gruppe Einzugsgebiet 4000).zip / Auge 4000 #14 (1987-12-23)(Amiga User Gruppe Einzugsgebiet 4000).adf / FuncKey1.1 / FuncKey.doc < prev    next >
Text File  |  1987-12-30  |  13KB  |  325 lines
  1.  
  2.                /*****************************************\
  3.                 *>                                     <*
  4.                 *>   The FuncKey Function Key Editor   <*
  5.                 *>             Version 1.1             <*
  6.                 *>   Copyright (c) 1987 by Anson Mah   <*
  7.                 *>                                     <*
  8.                \*****************************************/
  9.  
  10.                 This document must accompany the program.
  11.                   A completely distributable bundle is:
  12.                                FuncKey
  13.                                FuncKey.info
  14.                                Fhandler
  15.                                FuncKey.doc
  16.  
  17.  
  18.  
  19. ------------
  20. INTRODUCTION
  21. ------------
  22.  
  23.      FuncKey*  is a shareware  program  developed for the Amiga^.   A fee of
  24. $5 (five) is requested.  Commented source, in addition to the executable, is
  25. available for $10.  The source code will be supplied on disk, and purchasers
  26. of the  source  will  be entitled  to one  free  upgrade to both  source and
  27. executable  when or if another  version of  FuncKey is written.   When or if
  28. will be  determined  by the level of  response to  Version 1.00  of FuncKey.
  29. Please send payments and/or comments to the address below.
  30.  
  31.      FuncKey is  a tool that  will put an  end to the uselessness of the ten
  32. function keys sitting atop the Amiga keyboard.  This 'hotkey' utility allows
  33. each  function  key to be  programmed  with  up to five  different  keyboard
  34. equivalent  strings,  each string  able to hold up  to 79 characters and may
  35. contain control/escape sequences as well as left- and right-Amiga sequences.
  36. The five possible strings are accessed by combinations of Shift,  Alternate,
  37. Left-/Right-Amiga, and the function keys.
  38.  
  39.      Please note that FuncKey requires at least version 1.2 of AmigaDOS.
  40.  
  41.  
  42.  
  43. -----------
  44. What's New?
  45. -----------
  46.  
  47.      Version 1.1 adds some Intuition fun with the \ (back slash) introducer.
  48. See below in USING FuncKey - CONTROL PANEL for more information.
  49.  
  50.      Version 1.01 adds a pass-through  of an undefined  function key  to the
  51. Amiga  for  those  who  use  FuncKey  with  a program that also makes use of
  52. function keys.
  53.  
  54.  
  55.  
  56. ----------------
  57. STARTING FuncKey
  58. ----------------
  59.  
  60.      It is very important that the file called  Fhandler be placed in either
  61. the  c: directory or the  "current" directory.   If used from CLI, "current"
  62. refers to the  directory  that has been  CD'ed to  before executing FuncKey.
  63. If  used  from Workbench,  "current" refers to the  directory in  which  the
  64. FuncKey program lies.
  65.  
  66.      FuncKey may be started from  either the CLI (Command Line Interface) or
  67. Workbench.  From CLI, the syntax is
  68.  
  69.      [run] FuncKey [filename]
  70.  
  71. That is, the program may be started by simply entering  'FuncKey' or started
  72. as a background task by entering 'run FuncKey'.  In these cases, the FuncKey
  73. Control Panel will  appear, allowing the function keys to be programmed.  In
  74. addition, the filename of a FuncKey data file may be  entered on the command
  75. line.   This will initialize  the function keys with pre-recorded data,  and
  76. the  Control Panel  will not be brought up.   More on this  particular topic
  77. will be presented later.
  78.  
  79.      From Workbench, FuncKey may be started by double-clicking on the
  80. FuncKey  icon  (shaped like a function key) or a FuncKey data file icon.  In
  81. the  first  case, the Control Panel will appear, and in the second case, the
  82. function keys will have been programmed, so the Control Panel is not needed.
  83.  
  84.  
  85.  
  86.  
  87. -----------------------------
  88. USING FuncKey - CONTROL PANEL
  89. -----------------------------
  90.  
  91.      The  FuncKey Control Panel will  appear only  under the following three
  92. conditions:
  93.  
  94.      1> FuncKey is started in CLI with 'FuncKey', 'run FuncKey'
  95.      2> FuncKey is started with the the FuncKey icon in Workbench
  96.      3> RIGHT-Alt-HELP is depressed and the Control Panel is resident
  97.  
  98. An explanation of the Control Panel follow.  It assumes the knowledge of the
  99. terms 'gadget' and 'string gadget'.
  100.  
  101. String Gadgets F1 to F10:
  102.      The gadgets hold the definitions of the function keys.  Each definition
  103.      may be up  to 79 characters  in length.   Control and left-/right-Amiga
  104.      keys are specified by  preceding the character  desired with one of the
  105.      following three characters:
  106.  
  107.         ^  (caret)       introduces a control character ( eg ^m is CTRL-m )
  108.         {  (left brace)  introduces a left-Amiga sequence ( eg {m )
  109.         }  (right brace) introduces a right-Amiga sequence ( eg }q )
  110.         \  (back slash)  introduces one of these Intuition^ functions:
  111.            \w   activate next window
  112.            \W   activate next window and bring it to front
  113.            \f   bring active window to front
  114.            \s   bring next screen to front and activate it
  115.            Note:  FuncKey will ignore any illegal characters used here
  116.                   eg.  \e will be ignored
  117.  
  118.      The  characters ^ { } \  can be  generated  in a  definition  simply by
  119.      entering two of them consecutively. For example, {{ will result in a {.
  120.      Thus  the  sequences control-^, left-Amiga-{, and right-Amiga-} are not
  121.      possible in a definition.  (Any actual control characters  [represented
  122.      by a small box in the string gadget] are also not acknowledged.)
  123.  
  124. Key Qualifiers:
  125.      There are five gadgets labelled None, Shft, ALT, LAmi, RAmi.  These are
  126.      used to  select  which  particular set of  the possible  five are being
  127.      displayed  and edited.   For instance, to work with the  definitions of
  128.      the ten ALT-<function key> combinations, choose ALT.
  129.  
  130. Filename String Gadget:
  131.      A file can be  specified in which to  store or  from which  to retrieve
  132.      FuncKey  definitions.   The name of the  file is placed in this gadget. 
  133.      The default filename is s:func.key.
  134.  
  135. Load & Save Gadgets:
  136.      These are  used to load or save  function key  data from or to the file
  137.      specified in the filename string gadget.
  138.  
  139. I (Icon) Gadget:
  140.      This  gadget is used  in conjunction  with  the save feature.  If it is
  141.      selected, an icon will be created for the data file.  This icon, in the
  142.      Default Tool field,  points to the  FuncKey Control Panel  program with
  143.      ':FuncKey' as a default,  which specfies the root directory of the disk
  144.      that the data file icon is on.  This may be  changed with the Workbench
  145.      function Info.  (see the manual "Introduction to Amiga")
  146.      The  gadget  defaults  to an on  position if  FuncKey is  started  from
  147.      Workbench and to an off position if started from CLI.
  148.  
  149. Resident YES & NO Gadgets:
  150.      The Control Panel  may be kept  active in  memory  and be available for
  151.      instant recall.  To be sure that it is active, the YES gadget should be
  152.      chosen.  To have it terminate (and thus free some memory when it is not
  153.      in use), select  the NO gadget.   The default  is YES  when the Control
  154.      Panel is executed with 'run FuncKey' and  'run FuncKey <filename>' from
  155.      CLI and  when started  with the selection of a  data file icon from the
  156.      Workbench.   To recall the Control Panel if it is off but resident, use
  157.      the key sequence Right-Alt-HELP.
  158.  
  159. FuncKey ON & OFF Gadgets:
  160.      These  gadgets  allow  the  setting  of the  state of the  function key
  161.      handler  process.   If the  handler  is to be turned on,  choose the ON
  162.      gadget, otherwise choose the OFF gadget.  The default setting is ON.
  163.  
  164. Clear Gadget:
  165.      Selecting this will clear the Control Panel of all definitions.
  166.  
  167. Fetch Gadget:
  168.      This  fetches  the  definitions  currently  contained  in  the  handler
  169.      process.   This  is  useful if a  bad  edit  is  performed,  such as an
  170.      involuntary  Clear  of the  Control Panel.   Fetch will also return the
  171.      state  of the  handler,  and will adjust  the  FuncKey  ON/OFF  gadgets
  172.      accordingly.
  173.  
  174. Cancel Gadget:
  175.      Selecting  this  will cancel any  edits taken  place in a  function key
  176.      editing session.   All changes  made will not take place.   Cancel will
  177.      close the  Control Panel window  and will  remove it from memory if the
  178.      Resident NO gadget is selected.
  179.  
  180. <USE> Gadget:
  181.      When all  edits are  satisfactory,  choosing this will send the data to
  182.      the handler process and exit the Control Panel.  The Control Panel will
  183.      be removed from memory if the Resident NO gadget is selected.
  184.  
  185. <KILL> Gadget:
  186.      True to its name, the KILL function will terminate both the handler and
  187.      Control Panel processes, removing them from memory.
  188.  
  189.      If any  errors  occur  during any  Control Panel  functions,  a message
  190. describing the error will appear in the window title strip for approximately
  191. one second.
  192.  
  193.  
  194.  
  195. ------------------------------------
  196. USING FuncKey - FUNCTION KEY HANDLER
  197. ------------------------------------
  198.  
  199.      As  stated earlier,  the handler  program  Fhandler  must be  placed in
  200. either the  c: or current directory.   Fhandler cannot be executed by itself
  201. (a crash, aka a Guru Meditation, will result!).
  202.  
  203.      The handler process stays  resident in memory until it is KILLed by the
  204. Control Panel.   It may be toggled on and off by Right-Amiga-HELP.  However,
  205. if the Control Panel is resident also,  the sequence will bring the Panel up
  206. and toggling the state of the handler is performed on it instead.
  207.  
  208.      FuncKey Version 1.01  will also  pass through a key  press to the Amiga
  209. if a  function  key sequence  has  not  been defined.   For example,  if the
  210. handler is active, and F7 has not been defined with FuncKey, the F7 keypress
  211. is passed to the Amiga input stream untouched.   Thus with a program such as
  212. Scribble~,  which makes use of function keys, an undefined F7 will result in
  213. Scribble  toggling  underline  mode  on and off.   If F7 is instead defined,
  214. turning the handler  off is the only  way to make use of Scribble's  (or any
  215. other program's) function keys.
  216.  
  217.  
  218.  
  219. -------------------------
  220. RECOMMENDED CONFIGURATION
  221. -------------------------
  222.  
  223.      A recommended  FuncKey  environment is to  have the Fhandler program in
  224. the c:  directory and a call to FuncKey in the startup-sequence.   If a data
  225. file  is  often  used,  the  best  way  to  invoke  FuncKey  is  by  issuing
  226.  
  227.      FuncKey <filename>
  228.  
  229. from the  startup-sequence.   This will load up the handler,  initialize it,
  230. and remove the Control Panel, minimizing the use of memory.
  231.  
  232.  
  233.  
  234. --------------------------------------
  235. POSSIBLE PROBLEMS & SOLUTIONS FOR THEM
  236. --------------------------------------
  237.  
  238. Prob - Function keys are not responding!
  239. Soln - The key may not be defined, so check the Control Panel.
  240.      - The handler may  be  in the off state,  so press  Right-Amiga-HELP to
  241.        toggle it.
  242.  
  243. Prob - Function key doesn't produce the right result!
  244. Soln - The key may be defined with FuncKey and also used for another purpose
  245.        by another program.   Either turn the handler off  (with Right-Amiga-
  246.        HELP) or clear that key's definition from FuncKey, which will let the
  247.        Amiga see the key when the handler is active.
  248.  
  249. Prob - Selecting the data file icon doesn't seem to result in any actions!
  250. Soln - If all is proper,  the handler will have been loaded and initialized,
  251.        and trying out the function keys will show that.
  252.      - If a Workbench error occurs, it may be that the FuncKey Control Panel
  253.        program is in a  location other  than the root directory of the disk.
  254.        A change via the Workbench Info is in order.
  255.  
  256. Prob - (actually a bug)   24 bytes are lost every time the Control Panel and
  257.        the handler are terminated (KILLed).
  258. Soln - Gotta find a fix for it!
  259.  
  260.  
  261.  
  262. -------------------
  263. REFERENCE (CUT-OUT)
  264. -------------------
  265. -----8<-----cut here-----8<-----cut here-----8<-----cut here-----8<-----
  266.  
  267.  
  268. -----------------------------
  269. FuncKey Reference Information
  270. -----------------------------
  271.  
  272. Usage:  [run] FuncKey [filename]
  273.  
  274. Recalling Control Panel:  Right-Alt-HELP
  275.  
  276. Toggle state of function key handler:  Right-Alt-HELP
  277. (used when the Control Panel is not active)
  278.  
  279. Examples of definitions:
  280.      dir^m --> results in 'dir' followed by a carriage return
  281.      ^x    --> results in CTRL-x (clears the CLI command line)
  282.      ^c    --> results in CTRL-c (defines a BREAK key)
  283.      list  --> results in 'list'
  284.      {m    --> results in Left-Amiga-m
  285.      }q    --> results in Right-Amiga-q
  286.      \w    --> activates next window
  287.      \W    --> activates next window and brings it to front
  288.      \f    --> brings active window to front
  289.      \s    --> brings next screen to front (and activates it)
  290.      dir^m\Wlist^m  --> types 'dir<cr>' in one window and 'list<cr>'
  291.                         in the next
  292.      }}{{\\^^  -> results in '}{\^'
  293.  
  294. REMINDER: Fhandler must be in either the c: or current directory.
  295.  
  296.  
  297. -----8<-----cut here-----8<-----cut here-----8<-----cut here-----8<-----
  298.  
  299.  
  300.  
  301. --------------------
  302. AUTHOR'S ADDRESS(ES)
  303. --------------------
  304. Post (zzzz):   Anson Mah
  305.                2735 E. 2nd Ave.
  306.                Vancouver, B.C.
  307.                Canada  V5M 1E2
  308. Phone:         (604) 254-6849
  309.  
  310. uucp: (before Sept '87)   {anywhere}!ubc-vision!mdivax1!amah
  311.  
  312.       (after Sept '87)    {anywhere}!ubc-vision!ubc-bdcvax!mah
  313.  
  314. Bitnet:   USERAMAH@UBCMTSG
  315.  
  316.  
  317.  
  318. -----
  319. NOTES
  320. -------------------------------------------------------------------------
  321. *  FuncKey is Copyright (c) 1987 Anson Mah
  322. ~  Scribble! Copyright (c) 1986 Micro-Systems Software, Inc.
  323. ^  Amiga and Intuition are trademarks of Commodore Business Machines, Ltd.
  324. -------------------------------------------------------------------------
  325.